UtilitySpace

java.lang.Object
- negotiator.utility.UtilitySpace

Direct Known Subclasses:

OpponentModelUtilSpace, UtilitySpaceAdapter
```
public class UtilitySpace
extends java.lang.Object
```
Wouter: the utility space couples all objectives to weights and evaluators. A utilityspace currently is not bound to one agent. I can see some security issues with that... Wouter: this class is final to prevent users (students) to override the getUtility function with their own version of UtilitySpace Wouter 15nov: un-done the final, students may hack what they want, but they work with a copy anyway.

Author:

D. Tykhonov, K. Hindriks, W. Pasman

Field Summary

Fields
Modifier and Type Field and Description

protected Domain domain

Fields
Modifier and Type	Field and Description
`protected Domain`	`domain`

Constructor Summary

Constructors
Constructor and Description
`UtilitySpace()` Creates an empty utility space.
`UtilitySpace(Domain domain)` Creates a new utilityspace of the given domain.
`UtilitySpace(Domain domain, java.util.Map<Objective,Evaluator> fEvaluators)`
`UtilitySpace(Domain domain, java.lang.String fileName)` Create new default util space for a given domain.
`UtilitySpace(UtilitySpace us)` Copies the data from another UtilitySpace.

Method Summary

Methods
Modifier and Type	Method and Description
`Evaluator`	`addEvaluator(Objective obj)` Adds an evaluator to an objective or issue
`Evaluator`	`addEvaluator(Objective obj, Evaluator ev)` Sets an pair.
`void`	`checkReadyForNegotiation(Domain dom)` check if this utility space is ready for negotiation.
`Evaluator`	`DefaultEvaluator(Objective obj)` create a default evaluator for a given Objective.
`static double`	`discount(double util, double time, double discountFactor)` Computes: discountedUtil = util * Math.pow(discount, time).
`boolean`	`equals(java.lang.Object obj)`
`double`	`getDiscountFactor()`
`Domain`	`getDomain()`
`double`	`getEvaluation(int pIssueIndex, Bid bid)` Returns the utility of one issue in the bid.
`Evaluator`	`getEvaluator(int index)`
`java.util.Set<java.util.Map.Entry<Objective,Evaluator>>`	`getEvaluators()`
`java.lang.String`	`getFileName()`
`Objective`	`getIssue(int index)` Deprecated. Use getObjective
`Bid`	`getMaxUtilityBid()` Totally revised, brute-force search now.
`Bid`	`getMinUtilityBid()` Returns the the worst bid.
`int`	`getNrOfEvaluators()`
`Objective`	`getObjective(int index)` Returns the Objective or Issue at that index
`java.lang.Double`	`getReservationValue()` The reservation value is the least favourable point at which one will accept a negotiated agreement.
`double`	`getReservationValueUndiscounted()` Equivalent to `getReservationValue()`, but always returns a double value.
`double`	`getReservationValueWithDiscount(double time)` The discounted version of `getReservationValue()`.
`double`	`getReservationValueWithDiscount(Timeline timeline)` The discounted version of `getReservationValue()`.
`double`	`getUtility(Bid bid)`
`double`	`getUtilityWithDiscount(Bid bid, double time)`
`double`	`getUtilityWithDiscount(Bid bid, long timeAfterStart, long deadline)` Deprecated.
`double`	`getUtilityWithDiscount(Bid bid, Timeline timeline)` Let d in (0, 1) be the discount factor.
`double`	`getWeight(int issueID)`
`SimpleElement`	`getXMLRoot()`
`java.lang.String`	`IsComplete()` Wouter: this function should check that the domainSubtreeP is a subtree of the utilSubtreeP, and that all leaf nodes are complete.
`boolean`	`lock(Objective obj)` Place a lock on the weight of an objective or issue.
`java.util.Set<java.util.Map.Entry<Objective,Evaluator>>`	`normalizeChildren(Objective obj)` Normalizes the weights of objectives of the given objective so that they sum up to one.
`protected void`	`normalizeWeights(Objective currentRoot)`
`boolean`	`removeEvaluator(Objective obj)` Removes an evaluator.
`void`	`setDiscount(double newDiscount)`
`void`	`setReservationValue(double newRV)`
`double`	`setWeight(Objective objective, double weight)` Method used to set the weight of the given objective.
`void`	`setWeightSimple(Objective objective, double weight)` Method which sets the weight of an issue without checking normalization.
`java.lang.String`	`toString()`
`SimpleElement`	`toXML()` Creates an xml representation (in the form of a SimpleElements) of the utilityspace.
`boolean`	`unlock(Objective obj)` Clear a lock on the weight of an objective or issue.

Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - domain
```
protected Domain domain
```
- Constructor Detail
  - UtilitySpace
```
public UtilitySpace()
```
    Creates an empty utility space.
  - UtilitySpace
```
public UtilitySpace(Domain domain)
```
    Creates a new utilityspace of the given domain.
    
    Parameters:
    domain - for which the utilityspace should be specified.
  - UtilitySpace
```
public UtilitySpace(Domain domain,
            java.util.Map<Objective,Evaluator> fEvaluators)
```
  - UtilitySpace
```
public UtilitySpace(Domain domain,
            java.lang.String fileName)
             throws java.lang.Exception
```
    Create new default util space for a given domain.
    
    Parameters:
    domain -
    fileName - to read domain from. Set fileName to "" if no file available, in which case default evaluators are loaded..
    
    Throws:
    
    java.lang.Exception - if error occurs, e.g. if domain does not match the util space, or file not found.
  - UtilitySpace
```
public UtilitySpace(UtilitySpace us)
```
    Copies the data from another UtilitySpace.
    
    Parameters:
    us - utilityspace to be cloned.
- Method Detail
  - DefaultEvaluator
```
public Evaluator DefaultEvaluator(Objective obj)
```
    create a default evaluator for a given Objective. This function is placed here, and not in Objective, because the Objectives should not be loaded with utility space functionality. The price we pay for that is that we now have an ugly switch inside the code, losing some modularity.
    
    Parameters:
    obj - the objective to create an evaluator for
    
    Returns:
    the default evaluator
  - normalizeWeights
```
protected void normalizeWeights(Objective currentRoot)
```
  - checkReadyForNegotiation
```
public void checkReadyForNegotiation(Domain dom)
                              throws java.lang.Exception
```
    check if this utility space is ready for negotiation.
    
    Parameters:
    dom - is the domain in which nego is taking place
    
    Throws:
    
    java.lang.Exception - if utility space is incomplete (@see isComplete());
  - getXMLRoot
```
public SimpleElement getXMLRoot()
```
    Returns:
    XML root of this utilityspace.
  - getNrOfEvaluators
```
public final int getNrOfEvaluators()
```
    Returns:
    number of issues.
  - getEvaluator
```
public final Evaluator getEvaluator(int index)
```
    Parameters:
    index - The IDnumber of the Objective or Issue
    
    Returns:
    An Evaluator for the Objective or Issue.
  - getUtility
```
public double getUtility(Bid bid)
                  throws java.lang.Exception
```
    Parameters:
    bid - of which we are interested in its utility.
    
    Returns:
    undiscounted utility of the given bid.
    
    Throws:
    
    java.lang.Exception - when bid is incomplete or invalid.
  - getUtilityWithDiscount
```
@Deprecated
public double getUtilityWithDiscount(Bid bid,
                                       long timeAfterStart,
                                       long deadline)
                              throws java.lang.Exception
```
    Deprecated.
    
    Deprecated: uses old timing protocol.
    
    Parameters:
    bid -
    timeAfterStart -
    deadline -
    
    Returns:
    discounted utility.
    
    Throws:
    
    java.lang.Exception
  - getUtilityWithDiscount
```
public double getUtilityWithDiscount(Bid bid,
                            Timeline timeline)
```
    Let d in (0, 1) be the discount factor. (If d <= 0 or d >= 1, we assume that d = 1.) Let t in [0, 1] be the current time, as defined by the Timeline. We compute the discounted utility discountedUtility as follows: discountedUtility = originalUtility * d^t. For t = 0 the utility remains unchanged, and for t = 1 the original utility is multiplied by the discount factor. The effect is almost linear in between.
    
    Parameters:
    bid - of which we are interested in its utility.
    timeline - indicating the time passed in the negotiation.
    
    Returns:
    discounted utility.
  - getUtilityWithDiscount
```
public double getUtilityWithDiscount(Bid bid,
                            double time)
```
    Parameters:
    bid - of which we want to know the utility at the given time.
    time - at which we want to know the utility of the bid.
    
    Returns:
    discounted utility.
    See Also:
    getUtilityWithDiscount(Bid, Timeline)
  - discount
```
public static double discount(double util,
              double time,
              double discountFactor)
```
    Computes: discountedUtil = util * Math.pow(discount, time). Checks for bounds on the discount factor and time.
    
    Parameters:
    util - undiscounted utility.
    time - at which we want to know the discounted utility.
    discountFactor - of the preference profile.
    
    Returns:
    discounted version of the given utility at the given time.
  - getEvaluation
```
public final double getEvaluation(int pIssueIndex,
                   Bid bid)
                           throws java.lang.Exception
```
    Returns the utility of one issue in the bid. Note that this value is in the range [0,1] as it is not normalized by the issue weight.
    
    Parameters:
    pIssueIndex - of the issue.
    bid -
    
    Returns:
    evaluation of the value of the issue of the given bid.
    
    Throws:
    
    java.lang.Exception - if the bid or value is null.
  - getMaxUtilityBid
```
public final Bid getMaxUtilityBid()
                           throws java.lang.Exception
```
    Totally revised, brute-force search now.
    
    Returns:
    a bid with the maximum utility value attainable in this util space
    
    Throws:
    
    java.lang.Exception - if there is no bid at all in this util space.
  - getMinUtilityBid
```
public Bid getMinUtilityBid()
                     throws java.lang.Exception
```
    Returns the the worst bid.
    
    Returns:
    a bid with the lowest possible utility
    
    Throws:
    
    java.lang.Exception - if there is no bid at all in the util space
  - getWeight
```
public double getWeight(int issueID)
```
    Parameters:
    issueID - The Issue or Objective to get the weight from
    
    Returns:
    The weight, or -1 if the objective doesn't exist.
  - setWeightSimple
```
public void setWeightSimple(Objective objective,
                   double weight)
```
    Method which sets the weight of an issue without checking normalization. This is faster than setWeightSimple if normalization is ensured.
    
    Parameters:
    objective - of which the weights must be set.
    weight - to which the weight of the objective must be set.
  - setWeight
```
public double setWeight(Objective objective,
               double weight)
```
    Method used to set the weight of the given objective.
    
    Parameters:
    objective - of which the weights must be set.
    weight - to which the weight of the objective must be set.
    
    Returns:
    the new weight of the issue after normalization.
  - getIssue
```
public final Objective getIssue(int index)
```
    Deprecated. Use getObjective
    
    Parameters:
    index - The index of the issue to
    
    Returns:
    the indexed objective or issue
  - getObjective
```
public final Objective getObjective(int index)
```
    Returns the Objective or Issue at that index
    
    Parameters:
    index - The index of the Objective or Issue.
    
    Returns:
    An Objective or Issue.
  - getDomain
```
public final Domain getDomain()
```
    Returns:
    domain belonging to this preference profile.
  - addEvaluator
```
public final Evaluator addEvaluator(Objective obj)
```
    Adds an evaluator to an objective or issue
    
    Parameters:
    obj - The Objective or Issue to attach an Evaluator to.
    
    Returns:
    The new Evaluator.
  - addEvaluator
```
public final Evaluator addEvaluator(Objective obj,
                     Evaluator ev)
```
    Sets an pair. Replaces old evaluator for objective
    
    Parameters:
    obj - The Objective to attach an Evaluator to.
    ev - The Evaluator to attach.
    
    Returns:
    the given evaluator Wouter: what's the use of the return value???
  - getEvaluators
```
public final java.util.Set<java.util.Map.Entry<Objective,Evaluator>> getEvaluators()
```
    Returns:
    The set with all pairs of evaluators and objectives in this utilityspace.
  - lock
```
public final boolean lock(Objective obj)
```
    Place a lock on the weight of an objective or issue.
    
    Parameters:
    obj - The objective or issue that is about to have it's weight locked.
    
    Returns:
    true if succesfull, false If the objective doesn't have an evaluator yet.
  - unlock
```
public final boolean unlock(Objective obj)
```
    Clear a lock on the weight of an objective or issue.
    
    Parameters:
    obj - The objective or issue that is having it's lock cleared.
    
    Returns:
    true If the lock is cleared, false if the objective or issue doesn't have an evaluator yet.
  - normalizeChildren
```
public final java.util.Set<java.util.Map.Entry<Objective,Evaluator>> normalizeChildren(Objective obj)
```
    Normalizes the weights of objectives of the given objective so that they sum up to one.
    
    Parameters:
    obj - of which the weights must be normalized.
    
    Returns:
    all evaluators using getEvaluators().
  - removeEvaluator
```
public boolean removeEvaluator(Objective obj)
```
    Removes an evaluator.
    
    Parameters:
    obj - to be removed.
    
    Returns:
    true is successfully removed.
  - toXML
```
public SimpleElement toXML()
```
    Creates an xml representation (in the form of a SimpleElements) of the utilityspace.
    
    Returns:
    A representation of this utilityspace or null when there was an error.
  - IsComplete
```
public java.lang.String IsComplete()
```
    Wouter: this function *should* check that the domainSubtreeP is a subtree of the utilSubtreeP, and that all leaf nodes are complete. However currently we only check that all the leaf nodes are complete,
    
    Returns:
    null if util space is complete, else returns string containging explanation why not.
  - setReservationValue
```
public void setReservationValue(double newRV)
```
    Parameters:
    newRV - new reservation value.
  - setDiscount
```
public void setDiscount(double newDiscount)
```
    Parameters:
    newDiscount - new discount factor.
  - getReservationValue
```
public java.lang.Double getReservationValue()
```
    The reservation value is the least favourable point at which one will accept a negotiated agreement. Also sometimes referred to as the �walk away� point. This is value remains constant during the negotiation. However, by default, the reservation value descreases with time. To obtain the discounted version of the reservation value, use getReservationValueWithDiscount(Timeline).
    
    Returns:
    undiscounted reservation value of the preference profile (may be null).
  - getReservationValueUndiscounted
```
public double getReservationValueUndiscounted()
```
    Equivalent to getReservationValue(), but always returns a double value. When the original reservation value is null it returns the default value 0.
    
    Returns:
    undiscounted reservation value of the preference profile (never null).
    See Also:
    getReservationValue()
  - getReservationValueWithDiscount
```
public double getReservationValueWithDiscount(double time)
```
    The discounted version of getReservationValue().
    
    Parameters:
    time - at which we want to know the utility of the reservation value.
    
    Returns:
    discounted reservation value.
  - getReservationValueWithDiscount
```
public double getReservationValueWithDiscount(Timeline timeline)
```
    The discounted version of getReservationValue().
    
    Parameters:
    timeline - specifying the current time in the negotiation.
    
    Returns:
    discounted reservation value.
  - getFileName
```
public java.lang.String getFileName()
```
    Returns:
    filename of this preference profile.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object
  - getDiscountFactor
```
public final double getDiscountFactor()
```
    Returns:
    discount factor of this preference profile.

Class UtilitySpace

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

domain

Constructor Detail

UtilitySpace

UtilitySpace

UtilitySpace

UtilitySpace

UtilitySpace

Method Detail

DefaultEvaluator

normalizeWeights

checkReadyForNegotiation

getXMLRoot

getNrOfEvaluators

getEvaluator

getUtility

getUtilityWithDiscount

getUtilityWithDiscount

getUtilityWithDiscount

discount

getEvaluation

getMaxUtilityBid

getMinUtilityBid

getWeight

setWeightSimple

setWeight

getIssue

getObjective

getDomain

addEvaluator

addEvaluator

getEvaluators

lock

unlock

normalizeChildren

removeEvaluator

toXML

IsComplete

setReservationValue

setDiscount

getReservationValue

getReservationValueUndiscounted

getReservationValueWithDiscount

getReservationValueWithDiscount

getFileName

toString

equals

getDiscountFactor